---
title: 'API configuration (providers.yaml)'
sidebarTitle: 'API config (providers.yaml)'
icon: 'network-wired'
---

API configurations are listed in the `providers.yaml` file, located in the [Nango GitHub repository](https://github.com/NangoHQ/nango/blob/master/packages/providers/providers.yaml).

# Examples

<Tabs>

<Tab title="Hubspot">
```yaml
hubspot:
    display_name: HubSpot
    categories:
        - marketing
        - support
        - crm
    auth_mode: OAUTH2
    authorization_url: https://app.hubspot.com/oauth/authorize
    token_url: https://api.hubapi.com/oauth/v1/token
    connection_configuration:
        - portalId
    post_connection_script: hubspotPostConnection
    webhook_routing_script: hubspotWebhookRouting
    proxy:
        base_url: https://api.hubapi.com
        decompress: true
        paginate:
            type: cursor
            cursor_path_in_response: paging.next.after
            limit_name_in_request: limit
            cursor_name_in_request: after
            response_path: results
    docs: https://nango.dev/docs/integrations/all/hubspot
```

</Tab>

<Tab title="Salesforce">
```yaml
salesforce:
    display_name: Salesforce
    categories:
        - crm
    auth_mode: OAUTH2
    authorization_url: https://login.salesforce.com/services/oauth2/authorize
    token_url: https://login.salesforce.com/services/oauth2/token
    authorization_params:
        prompt: consent
    default_scopes:
        - offline_access
    token_response_metadata:
        - instance_url
    proxy:
        base_url: ${connectionConfig.instance_url}
    webhook_routing_script: salesforceWebhookRouting
    post_connection_script: salesforcePostConnection
    docs: https://nango.dev/docs/integrations/all/salesforce
    connection_config:
        instance_url:
            type: string
            title: Instance URL
            description: The instance URL of your Salesforce account
            format: uri
            pattern: '^https?://.*$'
```

</Tab>

<Tab title="Google">
```yaml
google:
    display_name: Google
    auth_mode: OAUTH2
    authorization_url: https://accounts.google.com/o/oauth2/v2/auth
    token_url: https://oauth2.googleapis.com/token
    authorization_params:
        response_type: code
        access_type: offline
        prompt: consent
    proxy:
        base_url: https://www.googleapis.com
        paginate:
            type: cursor
            cursor_path_in_response: nextPageToken
            limit_name_in_request: maxSize
            cursor_name_in_request: pageToken
            response_path: items
    docs: https://nango.dev/docs/integrations/all/google
```

</Tab>

<Tab title="Notion">
```yaml
notion:
    display_name: Notion
    categories:
        - knowledge-base
        - productivity
    auth_mode: OAUTH2
    authorization_url: https://api.notion.com/v1/oauth/authorize
    token_url: https://api.notion.com/v1/oauth/token
    authorization_params:
        response_type: code
        owner: user
    authorization_method: header
    body_format: json
    proxy:
        retry:
            after: 'Retry-After'
        base_url: https://api.notion.com
        headers:
            'Notion-Version': '2022-06-28'
        paginate:
            type: cursor
            cursor_path_in_response: next_cursor
            cursor_name_in_request: start_cursor
            limit_name_in_request: page_size
            response_path: results
    docs: https://nango.dev/docs/integrations/all/notion
```

</Tab>

<Tab title="Linear">
```yaml
linear:
    display_name: Linear
    categories:
        - productivity
        - ticketing
    auth_mode: OAUTH2
    authorization_url: https://linear.app/oauth/authorize
    token_url: https://api.linear.app/oauth/token
    scope_separator: ','
    authorization_params:
        prompt: consent
    proxy:
        base_url: https://api.linear.app
    disable_pkce: true
    webhook_routing_script: linearWebhookRouting
    post_connection_script: linearPostConnection
    webhook_user_defined_secret: true
    docs: https://nango.dev/docs/integrations/all/linear
```

</Tab>

<Tab title="Slack">
```yaml
slack:
    display_name: Slack
    categories:
        - productivity
    auth_mode: OAUTH2
    authorization_url: https://slack.com/oauth/v2/authorize
    token_url: https://slack.com/api/oauth.v2.access
    token_response_metadata:
        - incoming_webhook.url
        - incoming_webhook.channel
        - incoming_webhook.channel_id
        - bot_user_id
        - team.id
    proxy:
        base_url: https://slack.com/api
        paginate:
            type: cursor
            cursor_path_in_response: response_metadata.next_cursor
            cursor_name_in_request: cursor
            limit_name_in_request: limit
    webhook_routing_script: slackWebhookRouting
    docs: https://nango.dev/docs/integrations/all/slack
```

</Tab>

</Tabs>

# All configuration fields

<Tip>Looking for the JSON Schema, find it in our [GitHub](https://github.com/NangoHQ/nango/blob/master/scripts/validation/providers/schema.json)</Tip>

<ResponseField name="alias" type="string">
    Allows to extend the configuration of another API.
</ResponseField>

<ResponseField name="display_name" type="string" required>
    The display name of the provider, used in the UI.
</ResponseField>

<ResponseField name="auth_mode" type="string" >
    The authentication mode. Must be one of: "API_KEY", "APP", "APP_STORE", "BASIC", "NONE", "OAUTH1", "OAUTH2", "OAUTH2_CC", "CUSTOM", "TBA", "JWT", "BILL", "TWO_STEP", "SIGNATURE".
</ResponseField>

<ResponseField name="auth" type="object">
    Authentication configuration.
    <Expandable>
        <ResponseField name="response_type" type="string">
            The response type for authentication.
        </ResponseField>
    </Expandable>
</ResponseField>

<ResponseField name="authorization_method" type="string">
    The authorization method. Must be `header`
</ResponseField>

<ResponseField name="authorization_params" type="object">
    Query parameters of the authorization request.
    <Expandable>
        <ResponseField name="access_type" type="string">
            Possible value: "offline"
        </ResponseField>
        <ResponseField name="approval_prompt" type="string">
            Possible values: "auto", "force"
        </ResponseField>
        <ResponseField name="duration" type="string">
            Possible value: "permanent"
        </ResponseField>
        <ResponseField name="expiration" type="string">
            Possible value: "never"
        </ResponseField>
        <ResponseField name="force_verify" type="boolean">
            Whether to force verification
        </ResponseField>
        <ResponseField name="nonce" type="string">
            A unique string to be included in the request
        </ResponseField>
        <ResponseField name="prompt" type="string">
            Possible value: "consent"
        </ResponseField>
        <ResponseField name="response_mode" type="string">
            The mode of the response
        </ResponseField>
        <ResponseField name="response_type" type="string">
            The type of the response
        </ResponseField>
    </Expandable>
</ResponseField>

<ResponseField name="authorization_url" type="string">
    The URL to get the OAuth 2 credentials from the external API.
</ResponseField>

<ResponseField name="authorization_url_encoded" type="boolean">
    Should the `authorization_url` be encoded or not
</ResponseField>

<ResponseField name="authorization_url_replacements" type="object">
    An object containing key-value pairs for replacements in the authorization URL.
</ResponseField>

<ResponseField name="body_format" type="string">
    The format of the request body. e.g: `json`
</ResponseField>

<ResponseField name="categories" type="array">
    An array of strings representing the categories of the API.
</ResponseField>

<ResponseField name="connection_configuration" type="array">
    An array of strings representing the `connectionConfig` that are automatically populated by post-connection functions.
</ResponseField>

<ResponseField name="decode_url" type="boolean">
    Whether to decode the URL or not.
</ResponseField>

<ResponseField name="default_scopes" type="array">
    The minimum list of scopes that are necessary to connect to the API.
</ResponseField>

<ResponseField name="disable_pkce" type="boolean">
    Disables the [PKCE](https://oauth.net/2/pkce/) extension to the Authorization Code flow.
</ResponseField>

<ResponseField name="docs" type="string">
    The URL to the developer API documentation.
</ResponseField>

<ResponseField name="docs_connect" type="string">
    The URL to the end user documentation (e.g: how to connect).
</ResponseField>

<ResponseField name="post_connection_script" type="string">
    The name of the script to run after a connection is established.
</ResponseField>

<ResponseField name="proxy" type="object">
    Proxy configuration for the API.
    <Expandable>
        <ResponseField name="base_url" type="string">
            The base URL for the API.
        </ResponseField>
        <ResponseField name="decompress" type="boolean">
            Whether to decompress the response.
        </ResponseField>
        <ResponseField name="headers" type="object">
            Headers to be sent with each request.
        </ResponseField>
        <ResponseField name="paginate" type="object">
            Pagination configuration.
            <Expandable>
                <ResponseField name="cursor_name_in_request" type="string">
                    The name of the cursor parameter in the request.
                </ResponseField>
                <ResponseField name="cursor_path_in_response" type="string">
                    The path to the cursor value in the response.
                </ResponseField>
                <ResponseField name="limit_name_in_request" type="string">
                    The name of the limit parameter in the request.
                </ResponseField>
                <ResponseField name="link_rel_in_response_header" type="string">
                    The rel attribute of the link header for pagination.
                </ResponseField>
                <ResponseField name="link_path_in_response_body" type="string">
                    The path to the link in the response body.
                </ResponseField>
                <ResponseField name="offset_name_in_request" type="string">
                    The name of the offset parameter in the request.
                </ResponseField>
                <ResponseField name="offset_calculation_method" type="string">
                    The method to calculate the offset in the request. Must be one of: "per-page" or "by-response-size". Optional parameter that defaults to "by-response-size".
                </ResponseField>
                <ResponseField name="offset_start_value" type="number">
                    The starting value for the offset.
                </ResponseField>
                <ResponseField name="response_path" type="string">
                    The path to the paginated data in the response.
                </ResponseField>
                <ResponseField name="type" type="string">
                    The type of pagination. Must be one of: "link", "cursor", "offset".
                </ResponseField>
            </Expandable>
        </ResponseField>
        <ResponseField name="query" type="object">
            Query parameters to be sent with each request.
        </ResponseField>
        <ResponseField name="retry" type="object">
            Retry configuration.
            <Expandable>
                <ResponseField name="after" type="string">
                    The name of the rate-limit header, e.g. `after: 'X-Rate-Limit-Reset'`
                </ResponseField>
                <ResponseField name="at" type="string">
                    The name of the rate-limit header, e.g. `at: 'x-ratelimit-reset'`
                </ResponseField>
            </Expandable>
        </ResponseField>
        <ResponseField name="verification" type="object" required>
            Configure a HTTP call to verify if credentials are valid, only used for API Key and Basic auth.
            <Expandable>
                <ResponseField name="method" type="string">
                    The HTTP method for verification. Must be either "GET" or "POST".
                </ResponseField>
                <ResponseField name="endpoint" type="string" required>
                    The endpoint for verification.
                </ResponseField>
                <ResponseField name="base_url_override" type="string">
                    Override the base URL for verification.
                </ResponseField>
                <ResponseField name="headers" type="object">
                    Headers for the verification request.
                </ResponseField>
            </Expandable>
        </ResponseField>
    </Expandable>
</ResponseField>

<ResponseField name="redirect_uri_metadata" type="array">
    The metadata to capture from the callback request.
</ResponseField>

<ResponseField name="refresh_url" type="string">
    The URL used for refreshing the access token. Defaults to the `token_url`
</ResponseField>

<ResponseField name="refresh_params" type="object">
    Parameters used for refreshing the access token.
    <Expandable>
        <ResponseField name="grant_type" type="string">
            The grant type for refreshing the token. Must be "refresh_token".
        </ResponseField>
    </Expandable>
</ResponseField>

<ResponseField name="request_params" type="object">
    An object containing request parameters to pass to an authorization request.
</ResponseField>

<ResponseField name="request_url" type="string">
    The URL for making API an authorization request.
</ResponseField>

<ResponseField name="scope_separator" type="string">
    The separator used between scopes in the authorization request.
    Defaults to space, but some APIs sur `,` or `+`.
</ResponseField>

<ResponseField name="signature_method" type="string">
    The signature method used for OAuth 1.0. Must be either "HMAC-SHA1" or "PLAINTEXT".
</ResponseField>

<ResponseField name="token_expiration_buffer" type="number">
    A buffer time (in seconds) before the token expiration to trigger a refresh.
</ResponseField>

<ResponseField name="token_params" type="object">
    Parameters used for obtaining the access token.
    <Expandable>
        <ResponseField name="grant_type" type="string">
            The grant type for obtaining the token. Must be either "authorization_code" or "client_credentials".
        </ResponseField>
        <ResponseField name="request" type="string">
            Additional request information for obtaining the token.
        </ResponseField>
    </Expandable>
</ResponseField>

<ResponseField name="token_request_auth_method" type="string">
    The authentication method used for token requests. Must be either "basic" or "custom".
</ResponseField>

<ResponseField name="expires_in_unit" type="string">
    The unit of time for token expiration. Must be "milliseconds".
</ResponseField>

<ResponseField name="token_response_metadata" type="array">
    An array of strings representing metadata from the token response that will be saved in `connection.metadata`.
</ResponseField>

<ResponseField name="token_url" type="string">
    The URL to get the OAuth 2 credentials from the external API.
</ResponseField>

<ResponseField name="token_url_encoded" type="boolean">
    Should the `token_url` be encoded or not
</ResponseField>


<ResponseField name="webhook_user_defined_secret" type="boolean">
    Wether the webhook secret is set by the user.
</ResponseField>

<ResponseField name="webhook_routing_script" type="array">
    Specifies a script to handle external [webhooks](/guides/use-cases/webhooks).
</ResponseField>

<ResponseField name="authorization_url_fragment" type="string">
    Specifies a fragment to be appended to the authorization URL, typically used to modify the redirection flow or pass additional information in the URL before the query parameters.
</ResponseField>

<ResponseField name="connection_config" type="object">
    The list of properties available in `${connectionConfig}` and their validation.
    <Expandable>
        <ResponseField name="[name]" type="object">
            <Expandable>
                <ResponseField name="type" type="string" required>
                    The type of this value. Must be "string".
                </ResponseField>
                <ResponseField name="title" type="string" required>
                    The title of this value.
                </ResponseField>
                <ResponseField name="description" type="string" required>
                    The description of this value.
                </ResponseField>
                <ResponseField name="example" type="string">
                    An example of valid value to display in a UI.
                </ResponseField>
                <ResponseField name="pattern" type="string">
                    A regex pattern for the credential.
                </ResponseField>
                <ResponseField name="format" type="string">
                    The special format of this value (e.g: `hostname`, `uri`)
                </ResponseField>
                <ResponseField name="order" type="number">
                    The order in which this field should be displayed in a UI
                </ResponseField>
                <ResponseField name="doc_section" type="string">
                    The documentation section relative to `docs_connect`
                </ResponseField>
            </Expandable>
        </ResponseField>
    </Expandable>
</ResponseField>

<ResponseField name="credentials" type="object">
    The list of credentials and their validation, only filed if necessary (e.g: API_KEY, BASIC)
    <Expandable>
        <ResponseField name="[credential_name]" type="object">
            <Expandable>
                <ResponseField name="type" type="string" required>
                    The type of the credential. Must be "string".
                </ResponseField>
                <ResponseField name="title" type="string" required>
                    The title of the credential.
                </ResponseField>
                <ResponseField name="description" type="string" required>
                    The description of the credential.
                </ResponseField>
                <ResponseField name="example" type="string">
                    An example of the credential.
                </ResponseField>
                <ResponseField name="pattern" type="string">
                    A pattern for the credential.
                </ResponseField>
                <ResponseField name="format" type="string">
                    The format of the credential.
                </ResponseField>
                <ResponseField name="doc_section" type="string">
                    The documentation section for the credential.
                </ResponseField>
            </Expandable>
        </ResponseField>
    </Expandable>
</ResponseField>

<Tip>
**Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
</Tip>
